---
title: "Workflow Document State"
space: "Frappe Framework"
url: "https://support.aakvatech.com/Frappe Framework/workflow _document_state"
updated: "2026-07-22"
---

# Workflow Document State User Manual

## 1. Overview
The **Workflow Document State** module in **ERPNext** defines the allowed states of a document within a workflow and assigns roles responsible for transitioning between these states. It ensures structured document processing and role-based control.

## 2. Key Features
- **State Management:** Controls the document's progression through different workflow stages.
- **Document Status Control:** Defines whether a document is in draft, submitted, or canceled.
- **Role-Based Editing:** Limits editing rights to specific roles at each state.
- **Customizable Status Overrides:** Optionally prevents workflow states from modifying the document’s primary status.
- **Email Notifications:** Allows setting email templates for notifications at specific workflow stages.

## 3. Pre-Requisites
Before using the Workflow Document State module, ensure:
- **A Workflow is Defined** in ERPNext.
- **Roles are Assigned** to manage document transitions.
- **Workflow Actions are Configured** to support approvals or rejections.

## 4. Step-by-Step Usage
### Step 1: Creating a Workflow Document State
1. Navigate to **Workflow Document State** in ERPNext.
2. Click **New** to create a new workflow state.
3. Fill in the following details:
   - **State**: Name of the workflow state (e.g., Pending Approval, Approved, Rejected).
   - **Doc Status**: Choose from **Draft (0), Submitted (1), or Canceled (2)**.
   - **Update Field & Update Value**: Define if any field in the document should be updated when reaching this state.
   - **Only Allow Edit For**: Assign a specific role allowed to edit the document in this state.
   - **Next Action Email Template**: Select an email template to be sent when transitioning to this state.
   - **Is Optional State**: Enable if this state does not require a workflow action.
4. Click **Save** to store the state configuration.

### Step 2: Assigning States to a Workflow
1. Navigate to **Workflow** in ERPNext.
2. Open an existing workflow or create a new one.
3. In the **Workflow States** section, add the newly created **Workflow Document States**.
4. Define the allowed transitions between states and assign roles responsible for each transition.
5. Click **Save** to finalize the workflow configuration.

### Step 3: Applying Workflow Document States
1. Navigate to a document using a workflow (e.g., Purchase Order, Leave Application).
2. The document will display its **Current Workflow State**.
3. Based on assigned roles, users can transition the document to the next state.
4. If email notifications are configured, users will receive alerts about state changes.

## 5. Script Customizations
- **Customize Role Permissions:** Modify `allow_edit` settings to restrict document editing per role.
- **Trigger Automated Actions:** Use the `update_field` and `update_value` options to automate document changes when transitioning states.
- **Override Status Updates:** Enable `avoid_status_override` to prevent workflow status from overriding the document’s primary status.

## 6. Troubleshooting (Common Errors and Resolutions)
| Error | Cause | Solution |
|-------|-------|----------|
| *Workflow state does not change* | Missing transition in workflow settings | Ensure the state is mapped correctly in the workflow configuration |
| *Unauthorized to edit document* | Role restriction applied in `allow_edit` | Assign the correct role to allow edits |
| *Email alerts not sent* | No email template assigned | Ensure an email template is linked under `next_action_email_template` |

## 7. User Roles and Permissions
### Roles Available:
- **System Manager:** Full control over workflow states and configurations.
- **Workflow Approver:** Can transition documents between states.
- **Read-Only Users:** Can view workflow states but cannot modify them.

### Permissions Matrix
| Action | System Manager | Workflow Approver | Read-Only |
|--------|---------------|----------------|-----------|
| Create Workflow Document State | ✅ | ❌ | ❌ |
| Assign Document States to Workflows | ✅ | ✅ | ❌ |
| Transition Document Between States | ✅ | ✅ | ❌ |
| Edit Workflow State Properties | ✅ | ❌ | ❌ |

## 8. Key Notes
- Ensure **workflow document states** are correctly mapped to avoid workflow disruptions.
- Assign **editing permissions carefully** to maintain document integrity.
- **Email notifications** should be tested to confirm that they are sent to the right users.
- Regularly review workflow states to ensure seamless document processing.

---
This manual provides a complete guide to managing **Workflow Document States** in ERPNext. For further assistance, contact the **System Administrator** or refer to **Frappe Documentation**.